import asyncio
import time
from datetime import date, datetime, timedelta, timezone
from typing import TYPE_CHECKING, Any, Dict, List, Optional, Tuple, Union
from uuid import uuid4

if TYPE_CHECKING:
    from agno.tracing.schemas import Span, Trace

from agno.db.base import AsyncBaseDb, SessionType
from agno.db.mongo.utils import (
    apply_pagination,
    apply_sorting,
    bulk_upsert_metrics,
    calculate_date_metrics,
    create_collection_indexes_async,
    deserialize_cultural_knowledge_from_db,
    fetch_all_sessions_data,
    get_dates_to_calculate_metrics_for,
    serialize_cultural_knowledge_for_db,
)
from agno.db.schemas.culture import CulturalKnowledge
from agno.db.schemas.evals import EvalFilterType, EvalRunRecord, EvalType
from agno.db.schemas.knowledge import KnowledgeRow
from agno.db.schemas.memory import UserMemory
from agno.db.utils import deserialize_session_json_fields
from agno.session import AgentSession, Session, TeamSession, WorkflowSession
from agno.utils.log import log_debug, log_error, log_info
from agno.utils.string import generate_id

try:
    from motor.motor_asyncio import AsyncIOMotorClient, AsyncIOMotorCollection, AsyncIOMotorDatabase  # type: ignore

    MOTOR_AVAILABLE = True
except ImportError:
    MOTOR_AVAILABLE = False
    AsyncIOMotorClient = None  # type: ignore
    AsyncIOMotorCollection = None  # type: ignore
    AsyncIOMotorDatabase = None  # type: ignore

try:
    from pymongo import AsyncMongoClient  # type: ignore
    from pymongo.collection import AsyncCollection  # type: ignore
    from pymongo.database import AsyncDatabase  # type: ignore

    PYMONGO_ASYNC_AVAILABLE = True
except ImportError:
    PYMONGO_ASYNC_AVAILABLE = False
    AsyncMongoClient = None  # type: ignore
    AsyncDatabase = None  # type: ignore
    AsyncCollection = None  # type: ignore

try:
    from pymongo import ReturnDocument
    from pymongo.errors import OperationFailure
except ImportError:
    raise ImportError("`pymongo` not installed. Please install it using `pip install -U pymongo`")

# Ensure at least one async library is available
if not MOTOR_AVAILABLE and not PYMONGO_ASYNC_AVAILABLE:
    raise ImportError(
        "Neither `motor` nor PyMongo async is installed. "
        "Please install one of them using:\n"
        "  - `pip install -U 'pymongo>=4.9'` (recommended)"
        "  - `pip install -U motor` (legacy, deprecated)\n"
    )

# Create union types for client, database, and collection
if TYPE_CHECKING:
    if MOTOR_AVAILABLE and PYMONGO_ASYNC_AVAILABLE:
        AsyncMongoClientType = Union[AsyncIOMotorClient, AsyncMongoClient]  # type: ignore
        AsyncMongoDatabaseType = Union[AsyncIOMotorDatabase, AsyncDatabase]  # type: ignore
        AsyncMongoCollectionType = Union[AsyncIOMotorCollection, AsyncCollection]  # type: ignore
    elif MOTOR_AVAILABLE:
        AsyncMongoClientType = AsyncIOMotorClient  # type: ignore
        AsyncMongoDatabaseType = AsyncIOMotorDatabase  # type: ignore
        AsyncMongoCollectionType = AsyncIOMotorCollection  # type: ignore
    else:
        AsyncMongoClientType = AsyncMongoClient  # type: ignore
        AsyncMongoDatabaseType = AsyncDatabase  # type: ignore
        AsyncMongoCollectionType = AsyncCollection  # type: ignore
else:
    # Runtime type - use Any to avoid import issues
    AsyncMongoClientType = Any
    AsyncMongoDatabaseType = Any
    AsyncMongoCollectionType = Any


# Client type constants (defined before class to allow use in _detect_client_type)
_CLIENT_TYPE_MOTOR = "motor"
_CLIENT_TYPE_PYMONGO_ASYNC = "pymongo_async"
_CLIENT_TYPE_UNKNOWN = "unknown"


def _detect_client_type(client: Any) -> str:
    """Detect whether a client is Motor or PyMongo async."""
    if client is None:
        return _CLIENT_TYPE_UNKNOWN

    # Check PyMongo async
    if PYMONGO_ASYNC_AVAILABLE and AsyncMongoClient is not None:
        try:
            if isinstance(client, AsyncMongoClient):
                return _CLIENT_TYPE_PYMONGO_ASYNC
        except (TypeError, AttributeError):
            pass  # Fall through to next check

    if MOTOR_AVAILABLE and AsyncIOMotorClient is not None:
        try:
            if isinstance(client, AsyncIOMotorClient):
                return _CLIENT_TYPE_MOTOR
        except (TypeError, AttributeError):
            pass  # Fall through to fallback

    # Fallback to string matching only if isinstance fails
    # (should rarely happen, but useful for edge cases)
    client_type_name = type(client).__name__
    if "Motor" in client_type_name or "AsyncIOMotor" in client_type_name:
        return _CLIENT_TYPE_MOTOR
    elif "AsyncMongo" in client_type_name:
        return _CLIENT_TYPE_PYMONGO_ASYNC

    # Last resort: check module name
    module_name = type(client).__module__
    if "motor" in module_name:
        return _CLIENT_TYPE_MOTOR
    elif "pymongo" in module_name:
        return _CLIENT_TYPE_PYMONGO_ASYNC

    return _CLIENT_TYPE_UNKNOWN


class AsyncMongoDb(AsyncBaseDb):
    # Client type constants (class-level access to module constants)
    CLIENT_TYPE_MOTOR = _CLIENT_TYPE_MOTOR
    CLIENT_TYPE_PYMONGO_ASYNC = _CLIENT_TYPE_PYMONGO_ASYNC
    CLIENT_TYPE_UNKNOWN = _CLIENT_TYPE_UNKNOWN

    def __init__(
        self,
        db_client: Optional[Union["AsyncIOMotorClient", "AsyncMongoClient"]] = None,
        db_name: Optional[str] = None,
        db_url: Optional[str] = None,
        session_collection: Optional[str] = None,
        memory_collection: Optional[str] = None,
        metrics_collection: Optional[str] = None,
        eval_collection: Optional[str] = None,
        knowledge_collection: Optional[str] = None,
        culture_collection: Optional[str] = None,
        traces_collection: Optional[str] = None,
        spans_collection: Optional[str] = None,
        id: Optional[str] = None,
    ):
        """
        Async interface for interacting with a MongoDB database.

        Supports both Motor (legacy) and PyMongo async (recommended) clients.
        When both libraries are available, PyMongo async is preferred.

        Args:
            db_client (Optional[Union[AsyncIOMotorClient, AsyncMongoClient]]):
                The MongoDB async client to use. Can be either Motor's AsyncIOMotorClient
                or PyMongo's AsyncMongoClient. If not provided, a client will be created
                from db_url using the preferred available library.
            db_name (Optional[str]): The name of the database to use.
            db_url (Optional[str]): The database URL to connect to.
            session_collection (Optional[str]): Name of the collection to store sessions.
            memory_collection (Optional[str]): Name of the collection to store memories.
            metrics_collection (Optional[str]): Name of the collection to store metrics.
            eval_collection (Optional[str]): Name of the collection to store evaluation runs.
            knowledge_collection (Optional[str]): Name of the collection to store knowledge documents.
            culture_collection (Optional[str]): Name of the collection to store cultural knowledge.
            traces_collection (Optional[str]): Name of the collection to store traces.
            spans_collection (Optional[str]): Name of the collection to store spans.
            id (Optional[str]): ID of the database.

        Raises:
            ValueError: If neither db_url nor db_client is provided, or if db_client type is unsupported.
            ImportError: If neither motor nor pymongo async is installed.
        """
        if id is None:
            base_seed = db_url or str(db_client)
            db_name_suffix = db_name if db_name is not None else "agno"
            seed = f"{base_seed}#{db_name_suffix}"
            id = generate_id(seed)

        super().__init__(
            id=id,
            session_table=session_collection,
            memory_table=memory_collection,
            metrics_table=metrics_collection,
            eval_table=eval_collection,
            knowledge_table=knowledge_collection,
            culture_table=culture_collection,
            traces_table=traces_collection,
            spans_table=spans_collection,
        )

        # Detect client type if provided
        if db_client is not None:
            self._client_type = _detect_client_type(db_client)
            if self._client_type == self.CLIENT_TYPE_UNKNOWN:
                raise ValueError(
                    f"Unsupported MongoDB client type: {type(db_client).__name__}. "
                    "Only Motor (AsyncIOMotorClient) or PyMongo async (AsyncMongoClient) are supported."
                )
        else:
            # Auto-select preferred library when creating from URL
            # Prefer PyMongo async if available, fallback to Motor
            self._client_type = self.CLIENT_TYPE_PYMONGO_ASYNC if PYMONGO_ASYNC_AVAILABLE else self.CLIENT_TYPE_MOTOR

        # Store configuration for lazy initialization
        self._provided_client: Optional[AsyncMongoClientType] = db_client
        self.db_url: Optional[str] = db_url
        self.db_name: str = db_name if db_name is not None else "agno"

        if self._provided_client is None and self.db_url is None:
            raise ValueError("One of db_url or db_client must be provided")

        # Client and database will be lazily initialized per event loop
        self._client: Optional[AsyncMongoClientType] = None
        self._database: Optional[AsyncMongoDatabaseType] = None
        self._event_loop: Optional[asyncio.AbstractEventLoop] = None

    async def table_exists(self, table_name: str) -> bool:
        """Check if a collection with the given name exists in the MongoDB database.

        Args:
            table_name: Name of the collection to check

        Returns:
            bool: True if the collection exists in the database, False otherwise
        """
        collection_names = await self.database.list_collection_names()
        return table_name in collection_names

    async def _create_all_tables(self):
        """Create all configured MongoDB collections if they don't exist."""
        collections_to_create = [
            ("sessions", self.session_table_name),
            ("memories", self.memory_table_name),
            ("metrics", self.metrics_table_name),
            ("evals", self.eval_table_name),
            ("knowledge", self.knowledge_table_name),
            ("culture", self.culture_table_name),
        ]

        for collection_type, collection_name in collections_to_create:
            if collection_name and not await self.table_exists(collection_name):
                await self._get_collection(collection_type, create_collection_if_not_found=True)

    def _ensure_client(self) -> AsyncMongoClientType:
        """
        Ensure the MongoDB async client is valid for the current event loop.

        Both Motor's AsyncIOMotorClient and PyMongo's AsyncMongoClient are tied to
        the event loop they were created in. If we detect a new event loop, we need
        to refresh the client.

        Returns:
            Union[AsyncIOMotorClient, AsyncMongoClient]: A valid client for the current event loop.
        """
        try:
            current_loop = asyncio.get_running_loop()
        except RuntimeError:
            # No running loop, return existing client or create new one
            if self._client is None:
                if self._provided_client is not None:
                    self._client = self._provided_client
                elif self.db_url is not None:
                    # Create client based on detected type
                    if self._client_type == self.CLIENT_TYPE_PYMONGO_ASYNC and PYMONGO_ASYNC_AVAILABLE:
                        self._client = AsyncMongoClient(self.db_url)  # type: ignore
                    elif self._client_type == self.CLIENT_TYPE_MOTOR and MOTOR_AVAILABLE:
                        self._client = AsyncIOMotorClient(self.db_url)  # type: ignore
                    else:
                        raise RuntimeError(f"Client type '{self._client_type}' not available")
            return self._client  # type: ignore

        # Check if we're in a different event loop
        if self._event_loop is None or self._event_loop is not current_loop:
            # New event loop detected, create new client
            if self._provided_client is not None:
                # User provided a client, use it but warn them
                client_type_name = (
                    "AsyncMongoClient" if self._client_type == self.CLIENT_TYPE_PYMONGO_ASYNC else "AsyncIOMotorClient"
                )
                log_debug(
                    f"New event loop detected. Using provided {client_type_name}, "
                    "which may cause issues if it was created in a different event loop."
                )
                self._client = self._provided_client
            elif self.db_url is not None:
                if self._client_type == self.CLIENT_TYPE_PYMONGO_ASYNC and PYMONGO_ASYNC_AVAILABLE:
                    self._client = AsyncMongoClient(self.db_url)  # type: ignore
                elif self._client_type == self.CLIENT_TYPE_MOTOR and MOTOR_AVAILABLE:
                    self._client = AsyncIOMotorClient(self.db_url)  # type: ignore
                else:
                    raise RuntimeError(f"Client type '{self._client_type}' not available")

            self._event_loop = current_loop
            self._database = None  # Reset database reference
            # Clear collection caches and initialization flags when switching event loops
            for attr in list(vars(self).keys()):
                if attr.endswith("_collection") or attr.endswith("_initialized"):
                    delattr(self, attr)

        return self._client  # type: ignore

    @property
    def db_client(self) -> AsyncMongoClientType:
        """Get the MongoDB client, ensuring it's valid for the current event loop."""
        return self._ensure_client()

    @property
    def database(self) -> AsyncMongoDatabaseType:
        """Get the MongoDB database, ensuring it's valid for the current event loop."""
        try:
            current_loop = asyncio.get_running_loop()
            if self._database is None or self._event_loop != current_loop:
                self._database = self.db_client[self.db_name]  # type: ignore
        except RuntimeError:
            # No running loop - fallback to existing database or create new one
            if self._database is None:
                self._database = self.db_client[self.db_name]  # type: ignore
        return self._database

    # -- DB methods --

    def _should_reset_collection_cache(self) -> bool:
        """Check if collection cache should be reset due to event loop change."""
        try:
            current_loop = asyncio.get_running_loop()
            return self._event_loop is not current_loop
        except RuntimeError:
            return False

    async def _get_collection(
        self, table_type: str, create_collection_if_not_found: Optional[bool] = True
    ) -> Optional[AsyncMongoCollectionType]:
        """Get or create a collection based on table type.

        Args:
            table_type (str): The type of table to get or create.
            create_collection_if_not_found (Optional[bool]): Whether to create the collection if it doesn't exist.

        Returns:
            Union[AsyncIOMotorCollection, AsyncCollection]: The collection object.
        """
        # Ensure client is valid for current event loop before accessing collections
        _ = self.db_client  # This triggers _ensure_client()

        # Check if collections need to be reset due to event loop change
        reset_cache = self._should_reset_collection_cache()

        if table_type == "sessions":
            if reset_cache or not hasattr(self, "session_collection"):
                if self.session_table_name is None:
                    raise ValueError("Session collection was not provided on initialization")
                self.session_collection = await self._get_or_create_collection(
                    collection_name=self.session_table_name,
                    collection_type="sessions",
                    create_collection_if_not_found=create_collection_if_not_found,
                )
            return self.session_collection

        if table_type == "memories":
            if reset_cache or not hasattr(self, "memory_collection"):
                if self.memory_table_name is None:
                    raise ValueError("Memory collection was not provided on initialization")
                self.memory_collection = await self._get_or_create_collection(
                    collection_name=self.memory_table_name,
                    collection_type="memories",
                    create_collection_if_not_found=create_collection_if_not_found,
                )
            return self.memory_collection

        if table_type == "metrics":
            if reset_cache or not hasattr(self, "metrics_collection"):
                if self.metrics_table_name is None:
                    raise ValueError("Metrics collection was not provided on initialization")
                self.metrics_collection = await self._get_or_create_collection(
                    collection_name=self.metrics_table_name,
                    collection_type="metrics",
                    create_collection_if_not_found=create_collection_if_not_found,
                )
            return self.metrics_collection

        if table_type == "evals":
            if reset_cache or not hasattr(self, "eval_collection"):
                if self.eval_table_name is None:
                    raise ValueError("Eval collection was not provided on initialization")
                self.eval_collection = await self._get_or_create_collection(
                    collection_name=self.eval_table_name,
                    collection_type="evals",
                    create_collection_if_not_found=create_collection_if_not_found,
                )
            return self.eval_collection

        if table_type == "knowledge":
            if reset_cache or not hasattr(self, "knowledge_collection"):
                if self.knowledge_table_name is None:
                    raise ValueError("Knowledge collection was not provided on initialization")
                self.knowledge_collection = await self._get_or_create_collection(
                    collection_name=self.knowledge_table_name,
                    collection_type="knowledge",
                    create_collection_if_not_found=create_collection_if_not_found,
                )
            return self.knowledge_collection

        if table_type == "culture":
            if reset_cache or not hasattr(self, "culture_collection"):
                if self.culture_table_name is None:
                    raise ValueError("Culture collection was not provided on initialization")
                self.culture_collection = await self._get_or_create_collection(
                    collection_name=self.culture_table_name,
                    collection_type="culture",
                    create_collection_if_not_found=create_collection_if_not_found,
                )
            return self.culture_collection

        if table_type == "traces":
            if reset_cache or not hasattr(self, "traces_collection"):
                if self.trace_table_name is None:
                    raise ValueError("Traces collection was not provided on initialization")
                self.traces_collection = await self._get_or_create_collection(
                    collection_name=self.trace_table_name,
                    collection_type="traces",
                    create_collection_if_not_found=create_collection_if_not_found,
                )
            return self.traces_collection

        if table_type == "spans":
            if reset_cache or not hasattr(self, "spans_collection"):
                if self.span_table_name is None:
                    raise ValueError("Spans collection was not provided on initialization")
                self.spans_collection = await self._get_or_create_collection(
                    collection_name=self.span_table_name,
                    collection_type="spans",
                    create_collection_if_not_found=create_collection_if_not_found,
                )
            return self.spans_collection

        raise ValueError(f"Unknown table type: {table_type}")

    async def _get_or_create_collection(
        self, collection_name: str, collection_type: str, create_collection_if_not_found: Optional[bool] = True
    ) -> Optional[AsyncMongoCollectionType]:
        """Get or create a collection with proper indexes.

        Args:
            collection_name (str): The name of the collection to get or create.
            collection_type (str): The type of collection to get or create.
            create_collection_if_not_found (Optional[bool]): Whether to create the collection if it doesn't exist.

        Returns:
            Union[AsyncIOMotorCollection, AsyncCollection]: The collection object.
        """
        try:
            collection = self.database[collection_name]

            if not hasattr(self, f"_{collection_name}_initialized"):
                if not create_collection_if_not_found:
                    return None
                # Create indexes asynchronously for async MongoDB collections
                await create_collection_indexes_async(collection, collection_type)
                setattr(self, f"_{collection_name}_initialized", True)
                log_debug(f"Initialized collection '{collection_name}'")
            else:
                log_debug(f"Collection '{collection_name}' already initialized")

            return collection

        except Exception as e:
            log_error(f"Error getting collection {collection_name}: {e}")
            raise

    def get_latest_schema_version(self):
        """Get the latest version of the database schema."""
        pass

    def upsert_schema_version(self, version: str) -> None:
        """Upsert the schema version into the database."""
        pass

    # -- Session methods --

    async def delete_session(self, session_id: str) -> bool:
        """Delete a session from the database.

        Args:
            session_id (str): The ID of the session to delete.

        Returns:
            bool: True if the session was deleted, False otherwise.

        Raises:
            Exception: If there is an error deleting the session.
        """
        try:
            collection = await self._get_collection(table_type="sessions")
            if collection is None:
                return False

            result = await collection.delete_one({"session_id": session_id})
            if result.deleted_count == 0:
                log_debug(f"No session found to delete with session_id: {session_id}")
                return False
            else:
                log_debug(f"Successfully deleted session with session_id: {session_id}")
                return True

        except Exception as e:
            log_error(f"Error deleting session: {e}")
            raise e

    async def delete_sessions(self, session_ids: List[str]) -> None:
        """Delete multiple sessions from the database.

        Args:
            session_ids (List[str]): The IDs of the sessions to delete.
        """
        try:
            collection = await self._get_collection(table_type="sessions")
            if collection is None:
                return

            result = await collection.delete_many({"session_id": {"$in": session_ids}})
            log_debug(f"Successfully deleted {result.deleted_count} sessions")

        except Exception as e:
            log_error(f"Error deleting sessions: {e}")
            raise e

    async def get_session(
        self,
        session_id: str,
        session_type: SessionType,
        user_id: Optional[str] = None,
        deserialize: Optional[bool] = True,
    ) -> Optional[Union[Session, Dict[str, Any]]]:
        """Read a session from the database.

        Args:
            session_id (str): The ID of the session to get.
            session_type (SessionType): The type of session to get.
            user_id (Optional[str]): The ID of the user to get the session for.
            deserialize (Optional[bool]): Whether to serialize the session. Defaults to True.

        Returns:
            Union[Session, Dict[str, Any], None]:
                - When deserialize=True: Session object
                - When deserialize=False: Session dictionary

        Raises:
            Exception: If there is an error reading the session.
        """
        try:
            collection = await self._get_collection(table_type="sessions")
            if collection is None:
                return None

            query = {"session_id": session_id}
            if user_id is not None:
                query["user_id"] = user_id
            if session_type is not None:
                query["session_type"] = session_type

            result = await collection.find_one(query)
            if result is None:
                return None

            session = deserialize_session_json_fields(result)
            if not deserialize:
                return session

            if session_type == SessionType.AGENT:
                return AgentSession.from_dict(session)
            elif session_type == SessionType.TEAM:
                return TeamSession.from_dict(session)
            elif session_type == SessionType.WORKFLOW:
                return WorkflowSession.from_dict(session)
            else:
                raise ValueError(f"Invalid session type: {session_type}")

        except Exception as e:
            log_error(f"Exception reading session: {e}")
            raise e

    async def get_sessions(
        self,
        session_type: Optional[SessionType] = None,
        user_id: Optional[str] = None,
        component_id: Optional[str] = None,
        session_name: Optional[str] = None,
        start_timestamp: Optional[int] = None,
        end_timestamp: Optional[int] = None,
        limit: Optional[int] = None,
        page: Optional[int] = None,
        sort_by: Optional[str] = None,
        sort_order: Optional[str] = None,
        deserialize: Optional[bool] = True,
    ) -> Union[List[Session], Tuple[List[Dict[str, Any]], int]]:
        """Get all sessions.

        Args:
            session_type (Optional[SessionType]): The type of session to get.
            user_id (Optional[str]): The ID of the user to get the session for.
            component_id (Optional[str]): The ID of the component to get the session for.
            session_name (Optional[str]): The name of the session to filter by.
            start_timestamp (Optional[int]): The start timestamp to filter sessions by.
            end_timestamp (Optional[int]): The end timestamp to filter sessions by.
            limit (Optional[int]): The limit of the sessions to get.
            page (Optional[int]): The page number to get.
            sort_by (Optional[str]): The field to sort the sessions by.
            sort_order (Optional[str]): The order to sort the sessions by.
            deserialize (Optional[bool]): Whether to serialize the sessions. Defaults to True.

        Returns:
            Union[List[AgentSession], List[TeamSession], List[WorkflowSession], Tuple[List[Dict[str, Any]], int]]:
                - When deserialize=True: List of Session objects
                - When deserialize=False: List of session dictionaries and the total count

        Raises:
            Exception: If there is an error reading the sessions.
        """
        try:
            collection = await self._get_collection(table_type="sessions")
            if collection is None:
                return [] if deserialize else ([], 0)

            # Filtering
            query: Dict[str, Any] = {}
            if user_id is not None:
                query["user_id"] = user_id
            if session_type is not None:
                query["session_type"] = session_type
            if component_id is not None:
                if session_type == SessionType.AGENT:
                    query["agent_id"] = component_id
                elif session_type == SessionType.TEAM:
                    query["team_id"] = component_id
                elif session_type == SessionType.WORKFLOW:
                    query["workflow_id"] = component_id
            if start_timestamp is not None:
                query["created_at"] = {"$gte": start_timestamp}
            if end_timestamp is not None:
                if "created_at" in query:
                    query["created_at"]["$lte"] = end_timestamp
                else:
                    query["created_at"] = {"$lte": end_timestamp}
            if session_name is not None:
                query["session_data.session_name"] = {"$regex": session_name, "$options": "i"}

            # Get total count
            total_count = await collection.count_documents(query)

            cursor = collection.find(query)

            # Sorting
            sort_criteria = apply_sorting({}, sort_by, sort_order)
            if sort_criteria:
                cursor = cursor.sort(sort_criteria)

            # Pagination
            query_args = apply_pagination({}, limit, page)
            if query_args.get("skip"):
                cursor = cursor.skip(query_args["skip"])
            if query_args.get("limit"):
                cursor = cursor.limit(query_args["limit"])

            records = await cursor.to_list(length=None)
            if records is None:
                return [] if deserialize else ([], 0)
            sessions_raw = [deserialize_session_json_fields(record) for record in records]

            if not deserialize:
                return sessions_raw, total_count

            sessions: List[Union[AgentSession, TeamSession, WorkflowSession]] = []
            for record in sessions_raw:
                if session_type == SessionType.AGENT.value:
                    agent_session = AgentSession.from_dict(record)
                    if agent_session is not None:
                        sessions.append(agent_session)
                elif session_type == SessionType.TEAM.value:
                    team_session = TeamSession.from_dict(record)
                    if team_session is not None:
                        sessions.append(team_session)
                elif session_type == SessionType.WORKFLOW.value:
                    workflow_session = WorkflowSession.from_dict(record)
                    if workflow_session is not None:
                        sessions.append(workflow_session)

            return sessions

        except Exception as e:
            log_error(f"Exception reading sessions: {e}")
            raise e

    async def rename_session(
        self, session_id: str, session_type: SessionType, session_name: str, deserialize: Optional[bool] = True
    ) -> Optional[Union[Session, Dict[str, Any]]]:
        """Rename a session in the database.

        Args:
            session_id (str): The ID of the session to rename.
            session_type (SessionType): The type of session to rename.
            session_name (str): The new name of the session.
            deserialize (Optional[bool]): Whether to serialize the session. Defaults to True.

        Returns:
            Optional[Union[Session, Dict[str, Any]]]:
                - When deserialize=True: Session object
                - When deserialize=False: Session dictionary

        Raises:
            Exception: If there is an error renaming the session.
        """
        try:
            collection = await self._get_collection(table_type="sessions")
            if collection is None:
                return None

            try:
                result = await collection.find_one_and_update(
                    {"session_id": session_id},
                    {"$set": {"session_data.session_name": session_name, "updated_at": int(time.time())}},
                    return_document=ReturnDocument.AFTER,
                    upsert=False,
                )
            except OperationFailure:
                # If the update fails because session_data doesn't contain a session_name yet, we initialize session_data
                result = await collection.find_one_and_update(
                    {"session_id": session_id},
                    {"$set": {"session_data": {"session_name": session_name}, "updated_at": int(time.time())}},
                    return_document=ReturnDocument.AFTER,
                    upsert=False,
                )
            if not result:
                return None

            deserialized_session = deserialize_session_json_fields(result)

            if not deserialize:
                return deserialized_session

            if session_type == SessionType.AGENT.value:
                return AgentSession.from_dict(deserialized_session)
            elif session_type == SessionType.TEAM.value:
                return TeamSession.from_dict(deserialized_session)
            else:
                return WorkflowSession.from_dict(deserialized_session)

        except Exception as e:
            log_error(f"Exception renaming session: {e}")
            raise e

    async def upsert_session(
        self, session: Session, deserialize: Optional[bool] = True
    ) -> Optional[Union[Session, Dict[str, Any]]]:
        """Insert or update a session in the database.

        Args:
            session (Session): The session to upsert.
            deserialize (Optional[bool]): Whether to deserialize the session. Defaults to True.

        Returns:
            Optional[Union[Session, Dict[str, Any]]]: The upserted session.

        Raises:
            Exception: If there is an error upserting the session.
        """
        try:
            collection = await self._get_collection(table_type="sessions", create_collection_if_not_found=True)
            if collection is None:
                return None

            session_dict = session.to_dict()

            if isinstance(session, AgentSession):
                record = {
                    "session_id": session_dict.get("session_id"),
                    "session_type": SessionType.AGENT.value,
                    "agent_id": session_dict.get("agent_id"),
                    "user_id": session_dict.get("user_id"),
                    "runs": session_dict.get("runs"),
                    "agent_data": session_dict.get("agent_data"),
                    "session_data": session_dict.get("session_data"),
                    "summary": session_dict.get("summary"),
                    "metadata": session_dict.get("metadata"),
                    "created_at": session_dict.get("created_at"),
                    "updated_at": int(time.time()),
                }

                result = await collection.find_one_and_replace(
                    filter={"session_id": session_dict.get("session_id")},
                    replacement=record,
                    upsert=True,
                    return_document=ReturnDocument.AFTER,
                )
                if not result:
                    return None

                session = result  # type: ignore

                if not deserialize:
                    return session

                return AgentSession.from_dict(session)  # type: ignore

            elif isinstance(session, TeamSession):
                record = {
                    "session_id": session_dict.get("session_id"),
                    "session_type": SessionType.TEAM.value,
                    "team_id": session_dict.get("team_id"),
                    "user_id": session_dict.get("user_id"),
                    "runs": session_dict.get("runs"),
                    "team_data": session_dict.get("team_data"),
                    "session_data": session_dict.get("session_data"),
                    "summary": session_dict.get("summary"),
                    "metadata": session_dict.get("metadata"),
                    "created_at": session_dict.get("created_at"),
                    "updated_at": int(time.time()),
                }

                result = await collection.find_one_and_replace(
                    filter={"session_id": session_dict.get("session_id")},
                    replacement=record,
                    upsert=True,
                    return_document=ReturnDocument.AFTER,
                )
                if not result:
                    return None

                # MongoDB stores native objects, no deserialization needed for document fields
                session = result  # type: ignore

                if not deserialize:
                    return session

                return TeamSession.from_dict(session)  # type: ignore

            else:
                record = {
                    "session_id": session_dict.get("session_id"),
                    "session_type": SessionType.WORKFLOW.value,
                    "workflow_id": session_dict.get("workflow_id"),
                    "user_id": session_dict.get("user_id"),
                    "runs": session_dict.get("runs"),
                    "workflow_data": session_dict.get("workflow_data"),
                    "session_data": session_dict.get("session_data"),
                    "summary": session_dict.get("summary"),
                    "metadata": session_dict.get("metadata"),
                    "created_at": session_dict.get("created_at"),
                    "updated_at": int(time.time()),
                }

                result = await collection.find_one_and_replace(
                    filter={"session_id": session_dict.get("session_id")},
                    replacement=record,
                    upsert=True,
                    return_document=ReturnDocument.AFTER,
                )
                if not result:
                    return None

                session = result  # type: ignore

                if not deserialize:
                    return session

                return WorkflowSession.from_dict(session)  # type: ignore

        except Exception as e:
            log_error(f"Exception upserting session: {e}")
            raise e

    async def upsert_sessions(
        self, sessions: List[Session], deserialize: Optional[bool] = True, preserve_updated_at: bool = False
    ) -> List[Union[Session, Dict[str, Any]]]:
        """
        Bulk upsert multiple sessions for improved performance on large datasets.

        Args:
            sessions (List[Session]): List of sessions to upsert.
            deserialize (Optional[bool]): Whether to deserialize the sessions. Defaults to True.
            preserve_updated_at (bool): If True, preserve the updated_at from the session object.

        Returns:
            List[Union[Session, Dict[str, Any]]]: List of upserted sessions.

        Raises:
            Exception: If an error occurs during bulk upsert.
        """
        if not sessions:
            return []

        try:
            collection = await self._get_collection(table_type="sessions", create_collection_if_not_found=True)
            if collection is None:
                log_info("Sessions collection not available, falling back to individual upserts")
                return [
                    result
                    for session in sessions
                    if session is not None
                    for result in [await self.upsert_session(session, deserialize=deserialize)]
                    if result is not None
                ]

            from pymongo import ReplaceOne

            operations = []
            results: List[Union[Session, Dict[str, Any]]] = []

            for session in sessions:
                if session is None:
                    continue

                session_dict = session.to_dict()

                # Use preserved updated_at if flag is set and value exists, otherwise use current time
                updated_at = session_dict.get("updated_at") if preserve_updated_at else int(time.time())

                if isinstance(session, AgentSession):
                    record = {
                        "session_id": session_dict.get("session_id"),
                        "session_type": SessionType.AGENT.value,
                        "agent_id": session_dict.get("agent_id"),
                        "user_id": session_dict.get("user_id"),
                        "runs": session_dict.get("runs"),
                        "agent_data": session_dict.get("agent_data"),
                        "session_data": session_dict.get("session_data"),
                        "summary": session_dict.get("summary"),
                        "metadata": session_dict.get("metadata"),
                        "created_at": session_dict.get("created_at"),
                        "updated_at": updated_at,
                    }
                elif isinstance(session, TeamSession):
                    record = {
                        "session_id": session_dict.get("session_id"),
                        "session_type": SessionType.TEAM.value,
                        "team_id": session_dict.get("team_id"),
                        "user_id": session_dict.get("user_id"),
                        "runs": session_dict.get("runs"),
                        "team_data": session_dict.get("team_data"),
                        "session_data": session_dict.get("session_data"),
                        "summary": session_dict.get("summary"),
                        "metadata": session_dict.get("metadata"),
                        "created_at": session_dict.get("created_at"),
                        "updated_at": updated_at,
                    }
                elif isinstance(session, WorkflowSession):
                    record = {
                        "session_id": session_dict.get("session_id"),
                        "session_type": SessionType.WORKFLOW.value,
                        "workflow_id": session_dict.get("workflow_id"),
                        "user_id": session_dict.get("user_id"),
                        "runs": session_dict.get("runs"),
                        "workflow_data": session_dict.get("workflow_data"),
                        "session_data": session_dict.get("session_data"),
                        "summary": session_dict.get("summary"),
                        "metadata": session_dict.get("metadata"),
                        "created_at": session_dict.get("created_at"),
                        "updated_at": updated_at,
                    }
                else:
                    continue

                operations.append(
                    ReplaceOne(filter={"session_id": record["session_id"]}, replacement=record, upsert=True)
                )

            if operations:
                # Execute bulk write
                await collection.bulk_write(operations)

                # Fetch the results
                session_ids = [session.session_id for session in sessions if session and session.session_id]
                cursor = collection.find({"session_id": {"$in": session_ids}})

                async for doc in cursor:
                    session_dict = doc

                    if deserialize:
                        session_type = doc.get("session_type")
                        if session_type == SessionType.AGENT.value:
                            deserialized_agent_session = AgentSession.from_dict(session_dict)
                            if deserialized_agent_session is None:
                                continue
                            results.append(deserialized_agent_session)

                        elif session_type == SessionType.TEAM.value:
                            deserialized_team_session = TeamSession.from_dict(session_dict)
                            if deserialized_team_session is None:
                                continue
                            results.append(deserialized_team_session)

                        elif session_type == SessionType.WORKFLOW.value:
                            deserialized_workflow_session = WorkflowSession.from_dict(session_dict)
                            if deserialized_workflow_session is None:
                                continue
                            results.append(deserialized_workflow_session)
                    else:
                        results.append(session_dict)

            return results

        except Exception as e:
            log_error(f"Exception during bulk session upsert, falling back to individual upserts: {e}")

            # Fallback to individual upserts
            return [
                result
                for session in sessions
                if session is not None
                for result in [await self.upsert_session(session, deserialize=deserialize)]
                if result is not None
            ]

    # -- Memory methods --

    async def delete_user_memory(self, memory_id: str, user_id: Optional[str] = None):
        """Delete a user memory from the database.

        Args:
            memory_id (str): The ID of the memory to delete.
            user_id (Optional[str]): The ID of the user to verify ownership. If provided, only delete if the memory belongs to this user.

        Returns:
            bool: True if the memory was deleted, False otherwise.

        Raises:
            Exception: If there is an error deleting the memory.
        """
        try:
            collection = await self._get_collection(table_type="memories")
            if collection is None:
                return

            query = {"memory_id": memory_id}
            if user_id is not None:
                query["user_id"] = user_id

            result = await collection.delete_one(query)

            success = result.deleted_count > 0
            if success:
                log_debug(f"Successfully deleted memory id: {memory_id}")
            else:
                log_debug(f"No memory found with id: {memory_id}")

        except Exception as e:
            log_error(f"Error deleting memory: {e}")
            raise e

    async def delete_user_memories(self, memory_ids: List[str], user_id: Optional[str] = None) -> None:
        """Delete user memories from the database.

        Args:
            memory_ids (List[str]): The IDs of the memories to delete.
            user_id (Optional[str]): The ID of the user to verify ownership. If provided, only delete memories that belong to this user.

        Raises:
            Exception: If there is an error deleting the memories.
        """
        try:
            collection = await self._get_collection(table_type="memories")
            if collection is None:
                return

            query: Dict[str, Any] = {"memory_id": {"$in": memory_ids}}
            if user_id is not None:
                query["user_id"] = user_id

            result = await collection.delete_many(query)

            if result.deleted_count == 0:
                log_debug(f"No memories found with ids: {memory_ids}")

        except Exception as e:
            log_error(f"Error deleting memories: {e}")
            raise e

    async def get_all_memory_topics(self, user_id: Optional[str] = None) -> List[str]:
        """Get all memory topics from the database.

        Args:
            user_id (Optional[str]): The ID of the user to filter by. Defaults to None.

        Returns:
            List[str]: The topics.

        Raises:
            Exception: If there is an error getting the topics.
        """
        try:
            collection = await self._get_collection(table_type="memories")
            if collection is None:
                return []

            query = {}
            if user_id is not None:
                query["user_id"] = user_id

            topics = await collection.distinct("topics", query)
            return [topic for topic in topics if topic]

        except Exception as e:
            log_error(f"Exception reading from collection: {e}")
            raise e

    async def get_user_memory(
        self, memory_id: str, deserialize: Optional[bool] = True, user_id: Optional[str] = None
    ) -> Optional[UserMemory]:
        """Get a memory from the database.

        Args:
            memory_id (str): The ID of the memory to get.
            deserialize (Optional[bool]): Whether to serialize the memory. Defaults to True.
            user_id (Optional[str]): The ID of the user to verify ownership. If provided, only return the memory if it belongs to this user.

        Returns:
            Optional[UserMemory]:
                - When deserialize=True: UserMemory object
                - When deserialize=False: Memory dictionary

        Raises:
            Exception: If there is an error getting the memory.
        """
        try:
            collection = await self._get_collection(table_type="memories")
            if collection is None:
                return None

            query = {"memory_id": memory_id}
            if user_id is not None:
                query["user_id"] = user_id

            result = await collection.find_one(query)
            if result is None or not deserialize:
                return result

            # Remove MongoDB's _id field before creating UserMemory object
            result_filtered = {k: v for k, v in result.items() if k != "_id"}
            return UserMemory.from_dict(result_filtered)

        except Exception as e:
            log_error(f"Exception reading from collection: {e}")
            raise e

    async def get_user_memories(
        self,
        user_id: Optional[str] = None,
        agent_id: Optional[str] = None,
        team_id: Optional[str] = None,
        topics: Optional[List[str]] = None,
        search_content: Optional[str] = None,
        limit: Optional[int] = None,
        page: Optional[int] = None,
        sort_by: Optional[str] = None,
        sort_order: Optional[str] = None,
        deserialize: Optional[bool] = True,
    ) -> Union[List[UserMemory], Tuple[List[Dict[str, Any]], int]]:
        """Get all memories from the database as UserMemory objects.

        Args:
            user_id (Optional[str]): The ID of the user to get the memories for.
            agent_id (Optional[str]): The ID of the agent to get the memories for.
            team_id (Optional[str]): The ID of the team to get the memories for.
            topics (Optional[List[str]]): The topics to filter the memories by.
            search_content (Optional[str]): The content to filter the memories by.
            limit (Optional[int]): The limit of the memories to get.
            page (Optional[int]): The page number to get.
            sort_by (Optional[str]): The field to sort the memories by.
            sort_order (Optional[str]): The order to sort the memories by.
            deserialize (Optional[bool]): Whether to serialize the memories. Defaults to True.

        Returns:
            Union[List[UserMemory], Tuple[List[Dict[str, Any]], int]]:
                - When deserialize=True: List of UserMemory objects
                - When deserialize=False: Tuple of (memory dictionaries, total count)

        Raises:
            Exception: If there is an error getting the memories.
        """
        try:
            collection = await self._get_collection(table_type="memories")
            if collection is None:
                return [] if deserialize else ([], 0)

            query: Dict[str, Any] = {}
            if user_id is not None:
                query["user_id"] = user_id
            if agent_id is not None:
                query["agent_id"] = agent_id
            if team_id is not None:
                query["team_id"] = team_id
            if topics is not None:
                query["topics"] = {"$in": topics}
            if search_content is not None:
                query["memory"] = {"$regex": search_content, "$options": "i"}

            # Get total count
            total_count = await collection.count_documents(query)

            # Apply sorting
            sort_criteria = apply_sorting({}, sort_by, sort_order)

            # Apply pagination
            query_args = apply_pagination({}, limit, page)

            cursor = collection.find(query)
            if sort_criteria:
                cursor = cursor.sort(sort_criteria)
            if query_args.get("skip"):
                cursor = cursor.skip(query_args["skip"])
            if query_args.get("limit"):
                cursor = cursor.limit(query_args["limit"])

            records = await cursor.to_list(length=None)
            if not deserialize:
                return records, total_count

            # Remove MongoDB's _id field before creating UserMemory objects
            return [UserMemory.from_dict({k: v for k, v in record.items() if k != "_id"}) for record in records]

        except Exception as e:
            log_error(f"Exception reading from collection: {e}")
            raise e

    async def get_user_memory_stats(
        self,
        limit: Optional[int] = None,
        page: Optional[int] = None,
        user_id: Optional[str] = None,
    ) -> Tuple[List[Dict[str, Any]], int]:
        """Get user memories stats.

        Args:
            limit (Optional[int]): The limit of the memories to get.
            page (Optional[int]): The page number to get.
            user_id (Optional[str]): The ID of the user to filter by. Defaults to None.

        Returns:
            Tuple[List[Dict[str, Any]], int]: A tuple containing the memories stats and the total count.

        Raises:
            Exception: If there is an error getting the memories stats.
        """
        try:
            collection = await self._get_collection(table_type="memories")
            if collection is None:
                return [], 0

            match_stage: Dict[str, Any] = {"user_id": {"$ne": None}}
            if user_id is not None:
                match_stage["user_id"] = user_id

            pipeline = [
                {"$match": match_stage},
                {
                    "$group": {
                        "_id": "$user_id",
                        "total_memories": {"$sum": 1},
                        "last_memory_updated_at": {"$max": "$updated_at"},
                    }
                },
                {"$sort": {"last_memory_updated_at": -1}},
            ]

            # Get total count
            count_pipeline = pipeline + [{"$count": "total"}]
            count_result = await collection.aggregate(count_pipeline).to_list(length=1)
            total_count = count_result[0]["total"] if count_result else 0

            # Apply pagination
            if limit is not None:
                if page is not None:
                    pipeline.append({"$skip": (page - 1) * limit})  # type: ignore
                pipeline.append({"$limit": limit})  # type: ignore

            results = await collection.aggregate(pipeline).to_list(length=None)

            formatted_results = [
                {
                    "user_id": result["_id"],
                    "total_memories": result["total_memories"],
                    "last_memory_updated_at": result["last_memory_updated_at"],
                }
                for result in results
            ]

            return formatted_results, total_count

        except Exception as e:
            log_error(f"Exception getting user memory stats: {e}")
            raise e

    async def upsert_user_memory(
        self, memory: UserMemory, deserialize: Optional[bool] = True
    ) -> Optional[Union[UserMemory, Dict[str, Any]]]:
        """Upsert a user memory in the database.

        Args:
            memory (UserMemory): The memory to upsert.
            deserialize (Optional[bool]): Whether to serialize the memory. Defaults to True.

        Returns:
            Optional[Union[UserMemory, Dict[str, Any]]]:
                - When deserialize=True: UserMemory object
                - When deserialize=False: Memory dictionary

        Raises:
            Exception: If there is an error upserting the memory.
        """
        try:
            collection = await self._get_collection(table_type="memories", create_collection_if_not_found=True)
            if collection is None:
                return None

            if memory.memory_id is None:
                memory.memory_id = str(uuid4())

            update_doc = {
                "user_id": memory.user_id,
                "agent_id": memory.agent_id,
                "team_id": memory.team_id,
                "memory_id": memory.memory_id,
                "memory": memory.memory,
                "topics": memory.topics,
                "updated_at": int(time.time()),
            }

            result = await collection.replace_one({"memory_id": memory.memory_id}, update_doc, upsert=True)

            if result.upserted_id:
                update_doc["_id"] = result.upserted_id

            if not deserialize:
                return update_doc

            # Remove MongoDB's _id field before creating UserMemory object
            update_doc_filtered = {k: v for k, v in update_doc.items() if k != "_id"}
            return UserMemory.from_dict(update_doc_filtered)

        except Exception as e:
            log_error(f"Exception upserting user memory: {e}")
            raise e

    async def upsert_memories(
        self, memories: List[UserMemory], deserialize: Optional[bool] = True, preserve_updated_at: bool = False
    ) -> List[Union[UserMemory, Dict[str, Any]]]:
        """
        Bulk upsert multiple user memories for improved performance on large datasets.

        Args:
            memories (List[UserMemory]): List of memories to upsert.
            deserialize (Optional[bool]): Whether to deserialize the memories. Defaults to True.
            preserve_updated_at (bool): If True, preserve the updated_at from the memory object.

        Returns:
            List[Union[UserMemory, Dict[str, Any]]]: List of upserted memories.

        Raises:
            Exception: If an error occurs during bulk upsert.
        """
        if not memories:
            return []

        try:
            collection = await self._get_collection(table_type="memories", create_collection_if_not_found=True)
            if collection is None:
                log_info("Memories collection not available, falling back to individual upserts")
                return [
                    result
                    for memory in memories
                    if memory is not None
                    for result in [await self.upsert_user_memory(memory, deserialize=deserialize)]
                    if result is not None
                ]

            from pymongo import ReplaceOne

            operations = []
            results: List[Union[UserMemory, Dict[str, Any]]] = []

            current_time = int(time.time())
            for memory in memories:
                if memory is None:
                    continue

                if memory.memory_id is None:
                    memory.memory_id = str(uuid4())

                # Use preserved updated_at if flag is set and value exists, otherwise use current time
                updated_at = memory.updated_at if preserve_updated_at else current_time

                record = {
                    "user_id": memory.user_id,
                    "agent_id": memory.agent_id,
                    "team_id": memory.team_id,
                    "memory_id": memory.memory_id,
                    "memory": memory.memory,
                    "topics": memory.topics,
                    "input": memory.input,
                    "feedback": memory.feedback,
                    "created_at": memory.created_at,
                    "updated_at": updated_at,
                }

                operations.append(ReplaceOne(filter={"memory_id": memory.memory_id}, replacement=record, upsert=True))

            if operations:
                # Execute bulk write
                await collection.bulk_write(operations)

                # Fetch the results
                memory_ids = [memory.memory_id for memory in memories if memory and memory.memory_id]
                cursor = collection.find({"memory_id": {"$in": memory_ids}})

                async for doc in cursor:
                    if deserialize:
                        # Remove MongoDB's _id field before creating UserMemory object
                        doc_filtered = {k: v for k, v in doc.items() if k != "_id"}
                        results.append(UserMemory.from_dict(doc_filtered))
                    else:
                        results.append(doc)

            return results

        except Exception as e:
            log_error(f"Exception during bulk memory upsert, falling back to individual upserts: {e}")

            # Fallback to individual upserts
            return [
                result
                for memory in memories
                if memory is not None
                for result in [await self.upsert_user_memory(memory, deserialize=deserialize)]
                if result is not None
            ]

    async def clear_memories(self) -> None:
        """Delete all memories from the database.

        Raises:
            Exception: If an error occurs during deletion.
        """
        try:
            collection = await self._get_collection(table_type="memories")
            if collection is None:
                return

            await collection.delete_many({})

        except Exception as e:
            log_error(f"Exception deleting all memories: {e}")
            raise e

    # -- Cultural Knowledge methods --
    async def clear_cultural_knowledge(self) -> None:
        """Delete all cultural knowledge from the database.

        Raises:
            Exception: If an error occurs during deletion.
        """
        try:
            collection = await self._get_collection(table_type="culture")
            if collection is None:
                return

            await collection.delete_many({})

        except Exception as e:
            log_error(f"Exception deleting all cultural knowledge: {e}")
            raise e

    async def delete_cultural_knowledge(self, id: str) -> None:
        """Delete cultural knowledge by ID.

        Args:
            id (str): The ID of the cultural knowledge to delete.

        Raises:
            Exception: If an error occurs during deletion.
        """
        try:
            collection = await self._get_collection(table_type="culture")
            if collection is None:
                return

            await collection.delete_one({"id": id})
            log_debug(f"Deleted cultural knowledge with ID: {id}")

        except Exception as e:
            log_error(f"Error deleting cultural knowledge: {e}")
            raise e

    async def get_cultural_knowledge(
        self, id: str, deserialize: Optional[bool] = True
    ) -> Optional[Union[CulturalKnowledge, Dict[str, Any]]]:
        """Get cultural knowledge by ID.

        Args:
            id (str): The ID of the cultural knowledge to retrieve.
            deserialize (Optional[bool]): Whether to deserialize to CulturalKnowledge object. Defaults to True.

        Returns:
            Optional[Union[CulturalKnowledge, Dict[str, Any]]]: The cultural knowledge if found, None otherwise.

        Raises:
            Exception: If an error occurs during retrieval.
        """
        try:
            collection = await self._get_collection(table_type="culture")
            if collection is None:
                return None

            result = await collection.find_one({"id": id})
            if result is None:
                return None

            # Remove MongoDB's _id field
            result_filtered = {k: v for k, v in result.items() if k != "_id"}

            if not deserialize:
                return result_filtered

            return deserialize_cultural_knowledge_from_db(result_filtered)

        except Exception as e:
            log_error(f"Error getting cultural knowledge: {e}")
            raise e

    async def get_all_cultural_knowledge(
        self,
        agent_id: Optional[str] = None,
        team_id: Optional[str] = None,
        name: Optional[str] = None,
        limit: Optional[int] = None,
        page: Optional[int] = None,
        sort_by: Optional[str] = None,
        sort_order: Optional[str] = None,
        deserialize: Optional[bool] = True,
    ) -> Union[List[CulturalKnowledge], Tuple[List[Dict[str, Any]], int]]:
        """Get all cultural knowledge with filtering and pagination.

        Args:
            agent_id (Optional[str]): Filter by agent ID.
            team_id (Optional[str]): Filter by team ID.
            name (Optional[str]): Filter by name (case-insensitive partial match).
            limit (Optional[int]): Maximum number of results to return.
            page (Optional[int]): Page number for pagination.
            sort_by (Optional[str]): Field to sort by.
            sort_order (Optional[str]): Sort order ('asc' or 'desc').
            deserialize (Optional[bool]): Whether to deserialize to CulturalKnowledge objects. Defaults to True.

        Returns:
            Union[List[CulturalKnowledge], Tuple[List[Dict[str, Any]], int]]:
                - When deserialize=True: List of CulturalKnowledge objects
                - When deserialize=False: Tuple with list of dictionaries and total count

        Raises:
            Exception: If an error occurs during retrieval.
        """
        try:
            collection = await self._get_collection(table_type="culture")
            if collection is None:
                if not deserialize:
                    return [], 0
                return []

            # Build query
            query: Dict[str, Any] = {}
            if agent_id is not None:
                query["agent_id"] = agent_id
            if team_id is not None:
                query["team_id"] = team_id
            if name is not None:
                query["name"] = {"$regex": name, "$options": "i"}

            # Get total count for pagination
            total_count = await collection.count_documents(query)

            # Apply sorting
            sort_criteria = apply_sorting({}, sort_by, sort_order)

            # Apply pagination
            query_args = apply_pagination({}, limit, page)

            cursor = collection.find(query)
            if sort_criteria:
                cursor = cursor.sort(sort_criteria)
            if query_args.get("skip"):
                cursor = cursor.skip(query_args["skip"])
            if query_args.get("limit"):
                cursor = cursor.limit(query_args["limit"])

            # Remove MongoDB's _id field from all results
            results_filtered = [{k: v for k, v in item.items() if k != "_id"} async for item in cursor]

            if not deserialize:
                return results_filtered, total_count

            return [deserialize_cultural_knowledge_from_db(item) for item in results_filtered]

        except Exception as e:
            log_error(f"Error getting all cultural knowledge: {e}")
            raise e

    async def upsert_cultural_knowledge(
        self, cultural_knowledge: CulturalKnowledge, deserialize: Optional[bool] = True
    ) -> Optional[Union[CulturalKnowledge, Dict[str, Any]]]:
        """Upsert cultural knowledge in MongoDB.

        Args:
            cultural_knowledge (CulturalKnowledge): The cultural knowledge to upsert.
            deserialize (Optional[bool]): Whether to deserialize the result. Defaults to True.

        Returns:
            Optional[Union[CulturalKnowledge, Dict[str, Any]]]: The upserted cultural knowledge.

        Raises:
            Exception: If an error occurs during upsert.
        """
        try:
            collection = await self._get_collection(table_type="culture", create_collection_if_not_found=True)
            if collection is None:
                return None

            # Serialize content, categories, and notes into a dict for DB storage
            content_dict = serialize_cultural_knowledge_for_db(cultural_knowledge)

            # Create the document with serialized content
            update_doc = {
                "id": cultural_knowledge.id,
                "name": cultural_knowledge.name,
                "summary": cultural_knowledge.summary,
                "content": content_dict if content_dict else None,
                "metadata": cultural_knowledge.metadata,
                "input": cultural_knowledge.input,
                "created_at": cultural_knowledge.created_at,
                "updated_at": int(time.time()),
                "agent_id": cultural_knowledge.agent_id,
                "team_id": cultural_knowledge.team_id,
            }

            result = await collection.replace_one({"id": cultural_knowledge.id}, update_doc, upsert=True)

            if result.upserted_id:
                update_doc["_id"] = result.upserted_id

            # Remove MongoDB's _id field
            doc_filtered = {k: v for k, v in update_doc.items() if k != "_id"}

            if not deserialize:
                return doc_filtered

            return deserialize_cultural_knowledge_from_db(doc_filtered)

        except Exception as e:
            log_error(f"Error upserting cultural knowledge: {e}")
            raise e

    # -- Metrics methods --

    async def _get_all_sessions_for_metrics_calculation(
        self, start_timestamp: Optional[int] = None, end_timestamp: Optional[int] = None
    ) -> List[Dict[str, Any]]:
        """Get all sessions of all types for metrics calculation."""
        try:
            collection = await self._get_collection(table_type="sessions")
            if collection is None:
                return []

            query = {}
            if start_timestamp is not None:
                query["created_at"] = {"$gte": start_timestamp}
            if end_timestamp is not None:
                if "created_at" in query:
                    query["created_at"]["$lte"] = end_timestamp
                else:
                    query["created_at"] = {"$lte": end_timestamp}

            projection = {
                "user_id": 1,
                "session_data": 1,
                "runs": 1,
                "created_at": 1,
                "session_type": 1,
            }

            results = await collection.find(query, projection).to_list(length=None)
            return results

        except Exception as e:
            log_error(f"Exception reading from sessions collection: {e}")
            return []

    async def _get_metrics_calculation_starting_date(self, collection: AsyncMongoCollectionType) -> Optional[date]:
        """Get the first date for which metrics calculation is needed."""
        try:
            result = await collection.find_one({}, sort=[("date", -1)], limit=1)

            if result is not None:
                result_date = datetime.strptime(result["date"], "%Y-%m-%d").date()
                if result.get("completed"):
                    return result_date + timedelta(days=1)
                else:
                    return result_date

            # No metrics records. Return the date of the first recorded session.
            first_session_result = await self.get_sessions(
                sort_by="created_at", sort_order="asc", limit=1, deserialize=False
            )
            first_session_date = first_session_result[0][0]["created_at"] if first_session_result[0] else None  # type: ignore

            if first_session_date is None:
                return None

            return datetime.fromtimestamp(first_session_date, tz=timezone.utc).date()

        except Exception as e:
            log_error(f"Exception getting metrics calculation starting date: {e}")
            return None

    async def calculate_metrics(self) -> Optional[list[dict]]:
        """Calculate metrics for all dates without complete metrics."""
        try:
            collection = await self._get_collection(table_type="metrics", create_collection_if_not_found=True)
            if collection is None:
                return None

            starting_date = await self._get_metrics_calculation_starting_date(collection)
            if starting_date is None:
                log_info("No session data found. Won't calculate metrics.")
                return None

            dates_to_process = get_dates_to_calculate_metrics_for(starting_date)
            if not dates_to_process:
                log_info("Metrics already calculated for all relevant dates.")
                return None

            start_timestamp = int(
                datetime.combine(dates_to_process[0], datetime.min.time()).replace(tzinfo=timezone.utc).timestamp()
            )
            end_timestamp = int(
                datetime.combine(dates_to_process[-1] + timedelta(days=1), datetime.min.time())
                .replace(tzinfo=timezone.utc)
                .timestamp()
            )

            sessions = await self._get_all_sessions_for_metrics_calculation(
                start_timestamp=start_timestamp, end_timestamp=end_timestamp
            )
            all_sessions_data = fetch_all_sessions_data(
                sessions=sessions, dates_to_process=dates_to_process, start_timestamp=start_timestamp
            )
            if not all_sessions_data:
                log_info("No new session data found. Won't calculate metrics.")
                return None

            results = []
            metrics_records = []

            for date_to_process in dates_to_process:
                date_key = date_to_process.isoformat()
                sessions_for_date = all_sessions_data.get(date_key, {})

                # Skip dates with no sessions
                if not any(len(sessions) > 0 for sessions in sessions_for_date.values()):
                    continue

                metrics_record = calculate_date_metrics(date_to_process, sessions_for_date)
                metrics_records.append(metrics_record)

            if metrics_records:
                results = bulk_upsert_metrics(collection, metrics_records)  # type: ignore

            return results

        except Exception as e:
            log_error(f"Error calculating metrics: {e}")
            raise e

    async def get_metrics(
        self,
        starting_date: Optional[date] = None,
        ending_date: Optional[date] = None,
    ) -> Tuple[List[dict], Optional[int]]:
        """Get all metrics matching the given date range."""
        try:
            collection = await self._get_collection(table_type="metrics")
            if collection is None:
                return [], None

            query = {}
            if starting_date:
                query["date"] = {"$gte": starting_date.isoformat()}
            if ending_date:
                if "date" in query:
                    query["date"]["$lte"] = ending_date.isoformat()
                else:
                    query["date"] = {"$lte": ending_date.isoformat()}

            records = await collection.find(query).to_list(length=None)
            if not records:
                return [], None

            # Get the latest updated_at
            latest_updated_at = max(record.get("updated_at", 0) for record in records)

            return records, latest_updated_at

        except Exception as e:
            log_error(f"Error getting metrics: {e}")
            raise e

    # -- Knowledge methods --

    async def delete_knowledge_content(self, id: str):
        """Delete a knowledge row from the database.

        Args:
            id (str): The ID of the knowledge row to delete.

        Raises:
            Exception: If an error occurs during deletion.
        """
        try:
            collection = await self._get_collection(table_type="knowledge")
            if collection is None:
                return

            await collection.delete_one({"id": id})

            log_debug(f"Deleted knowledge content with id '{id}'")

        except Exception as e:
            log_error(f"Error deleting knowledge content: {e}")
            raise e

    async def get_knowledge_content(self, id: str) -> Optional[KnowledgeRow]:
        """Get a knowledge row from the database.

        Args:
            id (str): The ID of the knowledge row to get.

        Returns:
            Optional[KnowledgeRow]: The knowledge row, or None if it doesn't exist.

        Raises:
            Exception: If an error occurs during retrieval.
        """
        try:
            collection = await self._get_collection(table_type="knowledge")
            if collection is None:
                return None

            result = await collection.find_one({"id": id})
            if result is None:
                return None

            return KnowledgeRow.model_validate(result)

        except Exception as e:
            log_error(f"Error getting knowledge content: {e}")
            raise e

    async def get_knowledge_contents(
        self,
        limit: Optional[int] = None,
        page: Optional[int] = None,
        sort_by: Optional[str] = None,
        sort_order: Optional[str] = None,
    ) -> Tuple[List[KnowledgeRow], int]:
        """Get all knowledge contents from the database.

        Args:
            limit (Optional[int]): The maximum number of knowledge contents to return.
            page (Optional[int]): The page number.
            sort_by (Optional[str]): The column to sort by.
            sort_order (Optional[str]): The order to sort by.

        Returns:
            Tuple[List[KnowledgeRow], int]: The knowledge contents and total count.

        Raises:
            Exception: If an error occurs during retrieval.
        """
        try:
            collection = await self._get_collection(table_type="knowledge")
            if collection is None:
                return [], 0

            query: Dict[str, Any] = {}

            # Get total count
            total_count = await collection.count_documents(query)

            # Apply sorting
            sort_criteria = apply_sorting({}, sort_by, sort_order)

            # Apply pagination
            query_args = apply_pagination({}, limit, page)

            cursor = collection.find(query)
            if sort_criteria:
                cursor = cursor.sort(sort_criteria)
            if query_args.get("skip"):
                cursor = cursor.skip(query_args["skip"])
            if query_args.get("limit"):
                cursor = cursor.limit(query_args["limit"])

            records = await cursor.to_list(length=None)
            knowledge_rows = [KnowledgeRow.model_validate(record) for record in records]

            return knowledge_rows, total_count

        except Exception as e:
            log_error(f"Error getting knowledge contents: {e}")
            raise e

    async def upsert_knowledge_content(self, knowledge_row: KnowledgeRow):
        """Upsert knowledge content in the database.

        Args:
            knowledge_row (KnowledgeRow): The knowledge row to upsert.

        Returns:
            Optional[KnowledgeRow]: The upserted knowledge row, or None if the operation fails.

        Raises:
            Exception: If an error occurs during upsert.
        """
        try:
            collection = await self._get_collection(table_type="knowledge", create_collection_if_not_found=True)
            if collection is None:
                return None

            update_doc = knowledge_row.model_dump()
            await collection.replace_one({"id": knowledge_row.id}, update_doc, upsert=True)

            return knowledge_row

        except Exception as e:
            log_error(f"Error upserting knowledge content: {e}")
            raise e

    # -- Eval methods --

    async def create_eval_run(self, eval_run: EvalRunRecord) -> Optional[EvalRunRecord]:
        """Create an EvalRunRecord in the database."""
        try:
            collection = await self._get_collection(table_type="evals", create_collection_if_not_found=True)
            if collection is None:
                return None

            current_time = int(time.time())
            eval_dict = eval_run.model_dump()
            eval_dict["created_at"] = current_time
            eval_dict["updated_at"] = current_time

            await collection.insert_one(eval_dict)

            log_debug(f"Created eval run with id '{eval_run.run_id}'")

            return eval_run

        except Exception as e:
            log_error(f"Error creating eval run: {e}")
            raise e

    async def delete_eval_run(self, eval_run_id: str) -> None:
        """Delete an eval run from the database."""
        try:
            collection = await self._get_collection(table_type="evals")
            if collection is None:
                return

            result = await collection.delete_one({"run_id": eval_run_id})

            if result.deleted_count == 0:
                log_debug(f"No eval run found with ID: {eval_run_id}")
            else:
                log_debug(f"Deleted eval run with ID: {eval_run_id}")

        except Exception as e:
            log_error(f"Error deleting eval run {eval_run_id}: {e}")
            raise e

    async def delete_eval_runs(self, eval_run_ids: List[str]) -> None:
        """Delete multiple eval runs from the database."""
        try:
            collection = await self._get_collection(table_type="evals")
            if collection is None:
                return

            result = await collection.delete_many({"run_id": {"$in": eval_run_ids}})

            if result.deleted_count == 0:
                log_debug(f"No eval runs found with IDs: {eval_run_ids}")
            else:
                log_debug(f"Deleted {result.deleted_count} eval runs")

        except Exception as e:
            log_error(f"Error deleting eval runs {eval_run_ids}: {e}")
            raise e

    async def get_eval_run_raw(self, eval_run_id: str) -> Optional[Dict[str, Any]]:
        """Get an eval run from the database as a raw dictionary."""
        try:
            collection = await self._get_collection(table_type="evals")
            if collection is None:
                return None

            result = await collection.find_one({"run_id": eval_run_id})
            return result

        except Exception as e:
            log_error(f"Exception getting eval run {eval_run_id}: {e}")
            raise e

    async def get_eval_run(
        self, eval_run_id: str, deserialize: Optional[bool] = True
    ) -> Optional[Union[EvalRunRecord, Dict[str, Any]]]:
        """Get an eval run from the database.

        Args:
            eval_run_id (str): The ID of the eval run to get.
            deserialize (Optional[bool]): Whether to serialize the eval run. Defaults to True.

        Returns:
            Optional[Union[EvalRunRecord, Dict[str, Any]]]:
                - When deserialize=True: EvalRunRecord object
                - When deserialize=False: EvalRun dictionary

        Raises:
            Exception: If there is an error getting the eval run.
        """
        try:
            collection = await self._get_collection(table_type="evals")
            if collection is None:
                return None

            eval_run_raw = await collection.find_one({"run_id": eval_run_id})

            if not eval_run_raw:
                return None

            if not deserialize:
                return eval_run_raw

            return EvalRunRecord.model_validate(eval_run_raw)

        except Exception as e:
            log_error(f"Exception getting eval run {eval_run_id}: {e}")
            raise e

    async def get_eval_runs(
        self,
        limit: Optional[int] = None,
        page: Optional[int] = None,
        sort_by: Optional[str] = None,
        sort_order: Optional[str] = None,
        agent_id: Optional[str] = None,
        team_id: Optional[str] = None,
        workflow_id: Optional[str] = None,
        model_id: Optional[str] = None,
        filter_type: Optional[EvalFilterType] = None,
        eval_type: Optional[List[EvalType]] = None,
        deserialize: Optional[bool] = True,
    ) -> Union[List[EvalRunRecord], Tuple[List[Dict[str, Any]], int]]:
        """Get all eval runs from the database.

        Args:
            limit (Optional[int]): The maximum number of eval runs to return.
            page (Optional[int]): The page number to return.
            sort_by (Optional[str]): The field to sort by.
            sort_order (Optional[str]): The order to sort by.
            agent_id (Optional[str]): The ID of the agent to filter by.
            team_id (Optional[str]): The ID of the team to filter by.
            workflow_id (Optional[str]): The ID of the workflow to filter by.
            model_id (Optional[str]): The ID of the model to filter by.
            eval_type (Optional[List[EvalType]]): The type of eval to filter by.
            filter_type (Optional[EvalFilterType]): The type of filter to apply.
            deserialize (Optional[bool]): Whether to serialize the eval runs. Defaults to True.

        Returns:
            Union[List[EvalRunRecord], Tuple[List[Dict[str, Any]], int]]:
                - When deserialize=True: List of EvalRunRecord objects
                - When deserialize=False: List of eval run dictionaries and the total count

        Raises:
            Exception: If there is an error getting the eval runs.
        """
        try:
            collection = await self._get_collection(table_type="evals")
            if collection is None:
                return [] if deserialize else ([], 0)

            query: Dict[str, Any] = {}
            if agent_id is not None:
                query["agent_id"] = agent_id
            if team_id is not None:
                query["team_id"] = team_id
            if workflow_id is not None:
                query["workflow_id"] = workflow_id
            if model_id is not None:
                query["model_id"] = model_id
            if eval_type is not None and len(eval_type) > 0:
                query["eval_type"] = {"$in": eval_type}
            if filter_type is not None:
                if filter_type == EvalFilterType.AGENT:
                    query["agent_id"] = {"$ne": None}
                elif filter_type == EvalFilterType.TEAM:
                    query["team_id"] = {"$ne": None}
                elif filter_type == EvalFilterType.WORKFLOW:
                    query["workflow_id"] = {"$ne": None}

            # Get total count
            total_count = await collection.count_documents(query)

            # Apply default sorting by created_at desc if no sort parameters provided
            if sort_by is None:
                sort_criteria = [("created_at", -1)]
            else:
                sort_criteria = apply_sorting({}, sort_by, sort_order)

            # Apply pagination
            query_args = apply_pagination({}, limit, page)

            cursor = collection.find(query)
            if sort_criteria:
                cursor = cursor.sort(sort_criteria)
            if query_args.get("skip"):
                cursor = cursor.skip(query_args["skip"])
            if query_args.get("limit"):
                cursor = cursor.limit(query_args["limit"])

            records = await cursor.to_list(length=None)
            if not records:
                return [] if deserialize else ([], 0)

            if not deserialize:
                return records, total_count

            return [EvalRunRecord.model_validate(row) for row in records]

        except Exception as e:
            log_error(f"Exception getting eval runs: {e}")
            raise e

    async def rename_eval_run(
        self, eval_run_id: str, name: str, deserialize: Optional[bool] = True
    ) -> Optional[Union[EvalRunRecord, Dict[str, Any]]]:
        """Update the name of an eval run in the database.

        Args:
            eval_run_id (str): The ID of the eval run to update.
            name (str): The new name of the eval run.
            deserialize (Optional[bool]): Whether to serialize the eval run. Defaults to True.

        Returns:
            Optional[Union[EvalRunRecord, Dict[str, Any]]]:
                - When deserialize=True: EvalRunRecord object
                - When deserialize=False: EvalRun dictionary

        Raises:
            Exception: If there is an error updating the eval run.
        """
        try:
            collection = await self._get_collection(table_type="evals")
            if collection is None:
                return None

            result = await collection.find_one_and_update(
                {"run_id": eval_run_id}, {"$set": {"name": name, "updated_at": int(time.time())}}
            )

            log_debug(f"Renamed eval run with id '{eval_run_id}' to '{name}'")

            if not result or not deserialize:
                return result

            return EvalRunRecord.model_validate(result)

        except Exception as e:
            log_error(f"Error updating eval run name {eval_run_id}: {e}")
            raise e

    # --- Traces ---
    async def create_trace(self, trace: "Trace") -> None:
        """Create a single trace record in the database.

        Args:
            trace: The Trace object to store (one per trace_id).
        """
        try:
            collection = await self._get_collection(table_type="traces", create_collection_if_not_found=True)
            if collection is None:
                return

            # Check if trace already exists
            existing = await collection.find_one({"trace_id": trace.trace_id})

            if existing:
                # workflow (level 3) > team (level 2) > agent (level 1) > child/unknown (level 0)
                def get_component_level(
                    workflow_id: Optional[str], team_id: Optional[str], agent_id: Optional[str], name: str
                ) -> int:
                    # Check if name indicates a root span
                    is_root_name = ".run" in name or ".arun" in name

                    if not is_root_name:
                        return 0  # Child span (not a root)
                    elif workflow_id:
                        return 3  # Workflow root
                    elif team_id:
                        return 2  # Team root
                    elif agent_id:
                        return 1  # Agent root
                    else:
                        return 0  # Unknown

                existing_level = get_component_level(
                    existing.get("workflow_id"),
                    existing.get("team_id"),
                    existing.get("agent_id"),
                    existing.get("name", ""),
                )
                new_level = get_component_level(trace.workflow_id, trace.team_id, trace.agent_id, trace.name)

                # Only update name if new trace is from a higher or equal level
                should_update_name = new_level > existing_level

                # Parse existing start_time to calculate correct duration
                existing_start_time_str = existing.get("start_time")
                if isinstance(existing_start_time_str, str):
                    existing_start_time = datetime.fromisoformat(existing_start_time_str.replace("Z", "+00:00"))
                else:
                    existing_start_time = trace.start_time

                recalculated_duration_ms = int((trace.end_time - existing_start_time).total_seconds() * 1000)

                update_values: Dict[str, Any] = {
                    "end_time": trace.end_time.isoformat(),
                    "duration_ms": recalculated_duration_ms,
                    "status": trace.status,
                    "name": trace.name if should_update_name else existing.get("name"),
                }

                # Update context fields ONLY if new value is not None (preserve non-null values)
                if trace.run_id is not None:
                    update_values["run_id"] = trace.run_id
                if trace.session_id is not None:
                    update_values["session_id"] = trace.session_id
                if trace.user_id is not None:
                    update_values["user_id"] = trace.user_id
                if trace.agent_id is not None:
                    update_values["agent_id"] = trace.agent_id
                if trace.team_id is not None:
                    update_values["team_id"] = trace.team_id
                if trace.workflow_id is not None:
                    update_values["workflow_id"] = trace.workflow_id

                await collection.update_one({"trace_id": trace.trace_id}, {"$set": update_values})
            else:
                trace_dict = trace.to_dict()
                trace_dict.pop("total_spans", None)
                trace_dict.pop("error_count", None)
                await collection.insert_one(trace_dict)

        except Exception as e:
            log_error(f"Error creating trace: {e}")
            # Don't raise - tracing should not break the main application flow

    async def get_trace(
        self,
        trace_id: Optional[str] = None,
        run_id: Optional[str] = None,
    ):
        """Get a single trace by trace_id or other filters.

        Args:
            trace_id: The unique trace identifier.
            run_id: Filter by run ID (returns first match).

        Returns:
            Optional[Trace]: The trace if found, None otherwise.

        Note:
            If multiple filters are provided, trace_id takes precedence.
            For other filters, the most recent trace is returned.
        """
        try:
            from agno.tracing.schemas import Trace as TraceSchema

            collection = await self._get_collection(table_type="traces")
            if collection is None:
                return None

            # Get spans collection for aggregation
            spans_collection = await self._get_collection(table_type="spans")

            query: Dict[str, Any] = {}
            if trace_id:
                query["trace_id"] = trace_id
            elif run_id:
                query["run_id"] = run_id
            else:
                log_debug("get_trace called without any filter parameters")
                return None

            # Find trace with sorting by most recent
            result = await collection.find_one(query, sort=[("start_time", -1)])

            if result:
                # Calculate total_spans and error_count from spans collection
                total_spans = 0
                error_count = 0
                if spans_collection is not None:
                    total_spans = await spans_collection.count_documents({"trace_id": result["trace_id"]})
                    error_count = await spans_collection.count_documents(
                        {"trace_id": result["trace_id"], "status_code": "ERROR"}
                    )

                result["total_spans"] = total_spans
                result["error_count"] = error_count
                # Remove MongoDB's _id field
                result.pop("_id", None)
                return TraceSchema.from_dict(result)
            return None

        except Exception as e:
            log_error(f"Error getting trace: {e}")
            return None

    async def get_traces(
        self,
        run_id: Optional[str] = None,
        session_id: Optional[str] = None,
        user_id: Optional[str] = None,
        agent_id: Optional[str] = None,
        team_id: Optional[str] = None,
        workflow_id: Optional[str] = None,
        status: Optional[str] = None,
        start_time: Optional[datetime] = None,
        end_time: Optional[datetime] = None,
        limit: Optional[int] = 20,
        page: Optional[int] = 1,
    ) -> tuple[List, int]:
        """Get traces matching the provided filters with pagination.

        Args:
            run_id: Filter by run ID.
            session_id: Filter by session ID.
            user_id: Filter by user ID.
            agent_id: Filter by agent ID.
            team_id: Filter by team ID.
            workflow_id: Filter by workflow ID.
            status: Filter by status (OK, ERROR, UNSET).
            start_time: Filter traces starting after this datetime.
            end_time: Filter traces ending before this datetime.
            limit: Maximum number of traces to return per page.
            page: Page number (1-indexed).

        Returns:
            tuple[List[Trace], int]: Tuple of (list of matching traces, total count).
        """
        try:
            from agno.tracing.schemas import Trace as TraceSchema

            collection = await self._get_collection(table_type="traces")
            if collection is None:
                log_debug("Traces collection not found")
                return [], 0

            # Get spans collection for aggregation
            spans_collection = await self._get_collection(table_type="spans")

            # Build query
            query: Dict[str, Any] = {}
            if run_id:
                query["run_id"] = run_id
            if session_id:
                query["session_id"] = session_id
            if user_id:
                query["user_id"] = user_id
            if agent_id:
                query["agent_id"] = agent_id
            if team_id:
                query["team_id"] = team_id
            if workflow_id:
                query["workflow_id"] = workflow_id
            if status:
                query["status"] = status
            if start_time:
                query["start_time"] = {"$gte": start_time.isoformat()}
            if end_time:
                if "end_time" in query:
                    query["end_time"]["$lte"] = end_time.isoformat()
                else:
                    query["end_time"] = {"$lte": end_time.isoformat()}

            # Get total count
            total_count = await collection.count_documents(query)

            # Apply pagination
            skip = ((page or 1) - 1) * (limit or 20)
            cursor = collection.find(query).sort("start_time", -1).skip(skip).limit(limit or 20)

            results = await cursor.to_list(length=None)

            traces = []
            for row in results:
                # Calculate total_spans and error_count from spans collection
                total_spans = 0
                error_count = 0
                if spans_collection is not None:
                    total_spans = await spans_collection.count_documents({"trace_id": row["trace_id"]})
                    error_count = await spans_collection.count_documents(
                        {"trace_id": row["trace_id"], "status_code": "ERROR"}
                    )

                row["total_spans"] = total_spans
                row["error_count"] = error_count
                # Remove MongoDB's _id field
                row.pop("_id", None)
                traces.append(TraceSchema.from_dict(row))

            return traces, total_count

        except Exception as e:
            log_error(f"Error getting traces: {e}")
            return [], 0

    async def get_trace_stats(
        self,
        user_id: Optional[str] = None,
        agent_id: Optional[str] = None,
        team_id: Optional[str] = None,
        workflow_id: Optional[str] = None,
        start_time: Optional[datetime] = None,
        end_time: Optional[datetime] = None,
        limit: Optional[int] = 20,
        page: Optional[int] = 1,
    ) -> tuple[List[Dict[str, Any]], int]:
        """Get trace statistics grouped by session.

        Args:
            user_id: Filter by user ID.
            agent_id: Filter by agent ID.
            team_id: Filter by team ID.
            workflow_id: Filter by workflow ID.
            start_time: Filter sessions with traces created after this datetime.
            end_time: Filter sessions with traces created before this datetime.
            limit: Maximum number of sessions to return per page.
            page: Page number (1-indexed).

        Returns:
            tuple[List[Dict], int]: Tuple of (list of session stats dicts, total count).
                Each dict contains: session_id, user_id, agent_id, team_id, total_traces,
                workflow_id, first_trace_at, last_trace_at.
        """
        try:
            collection = await self._get_collection(table_type="traces")
            if collection is None:
                log_debug("Traces collection not found")
                return [], 0

            # Build match stage
            match_stage: Dict[str, Any] = {"session_id": {"$ne": None}}
            if user_id:
                match_stage["user_id"] = user_id
            if agent_id:
                match_stage["agent_id"] = agent_id
            if team_id:
                match_stage["team_id"] = team_id
            if workflow_id:
                match_stage["workflow_id"] = workflow_id
            if start_time:
                match_stage["created_at"] = {"$gte": start_time.isoformat()}
            if end_time:
                if "created_at" in match_stage:
                    match_stage["created_at"]["$lte"] = end_time.isoformat()
                else:
                    match_stage["created_at"] = {"$lte": end_time.isoformat()}

            # Build aggregation pipeline
            pipeline: List[Dict[str, Any]] = [
                {"$match": match_stage},
                {
                    "$group": {
                        "_id": "$session_id",
                        "user_id": {"$first": "$user_id"},
                        "agent_id": {"$first": "$agent_id"},
                        "team_id": {"$first": "$team_id"},
                        "workflow_id": {"$first": "$workflow_id"},
                        "total_traces": {"$sum": 1},
                        "first_trace_at": {"$min": "$created_at"},
                        "last_trace_at": {"$max": "$created_at"},
                    }
                },
                {"$sort": {"last_trace_at": -1}},
            ]

            # Get total count
            count_pipeline = pipeline + [{"$count": "total"}]
            count_result = await collection.aggregate(count_pipeline).to_list(length=1)
            total_count = count_result[0]["total"] if count_result else 0

            # Apply pagination
            skip = ((page or 1) - 1) * (limit or 20)
            pipeline.append({"$skip": skip})
            pipeline.append({"$limit": limit or 20})

            results = await collection.aggregate(pipeline).to_list(length=None)

            # Convert to list of dicts with datetime objects
            stats_list = []
            for row in results:
                # Convert ISO strings to datetime objects
                first_trace_at_str = row["first_trace_at"]
                last_trace_at_str = row["last_trace_at"]

                # Parse ISO format strings to datetime objects
                first_trace_at = datetime.fromisoformat(first_trace_at_str.replace("Z", "+00:00"))
                last_trace_at = datetime.fromisoformat(last_trace_at_str.replace("Z", "+00:00"))

                stats_list.append(
                    {
                        "session_id": row["_id"],
                        "user_id": row["user_id"],
                        "agent_id": row["agent_id"],
                        "team_id": row["team_id"],
                        "workflow_id": row["workflow_id"],
                        "total_traces": row["total_traces"],
                        "first_trace_at": first_trace_at,
                        "last_trace_at": last_trace_at,
                    }
                )

            return stats_list, total_count

        except Exception as e:
            log_error(f"Error getting trace stats: {e}")
            return [], 0

    # --- Spans ---
    async def create_span(self, span: "Span") -> None:
        """Create a single span in the database.

        Args:
            span: The Span object to store.
        """
        try:
            collection = await self._get_collection(table_type="spans", create_collection_if_not_found=True)
            if collection is None:
                return

            await collection.insert_one(span.to_dict())

        except Exception as e:
            log_error(f"Error creating span: {e}")

    async def create_spans(self, spans: List) -> None:
        """Create multiple spans in the database as a batch.

        Args:
            spans: List of Span objects to store.
        """
        if not spans:
            return

        try:
            collection = await self._get_collection(table_type="spans", create_collection_if_not_found=True)
            if collection is None:
                return

            span_dicts = [span.to_dict() for span in spans]
            await collection.insert_many(span_dicts)

        except Exception as e:
            log_error(f"Error creating spans batch: {e}")

    async def get_span(self, span_id: str):
        """Get a single span by its span_id.

        Args:
            span_id: The unique span identifier.

        Returns:
            Optional[Span]: The span if found, None otherwise.
        """
        try:
            from agno.tracing.schemas import Span as SpanSchema

            collection = await self._get_collection(table_type="spans")
            if collection is None:
                return None

            result = await collection.find_one({"span_id": span_id})
            if result:
                # Remove MongoDB's _id field
                result.pop("_id", None)
                return SpanSchema.from_dict(result)
            return None

        except Exception as e:
            log_error(f"Error getting span: {e}")
            return None

    async def get_spans(
        self,
        trace_id: Optional[str] = None,
        parent_span_id: Optional[str] = None,
        limit: Optional[int] = 1000,
    ) -> List:
        """Get spans matching the provided filters.

        Args:
            trace_id: Filter by trace ID.
            parent_span_id: Filter by parent span ID.
            limit: Maximum number of spans to return.

        Returns:
            List[Span]: List of matching spans.
        """
        try:
            from agno.tracing.schemas import Span as SpanSchema

            collection = await self._get_collection(table_type="spans")
            if collection is None:
                return []

            # Build query
            query: Dict[str, Any] = {}
            if trace_id:
                query["trace_id"] = trace_id
            if parent_span_id:
                query["parent_span_id"] = parent_span_id

            cursor = collection.find(query).limit(limit or 1000)
            results = await cursor.to_list(length=None)

            spans = []
            for row in results:
                # Remove MongoDB's _id field
                row.pop("_id", None)
                spans.append(SpanSchema.from_dict(row))

            return spans

        except Exception as e:
            log_error(f"Error getting spans: {e}")
            return []
